Oracle TimesTen In-Memory Database C開発者およびリファレンス・ガイド

ttXlaCommit

説明

ハンドルに対して適用中の現行のトランザクションをコミットします。トランザクションが完了しているかどうかに関係なく、このルーチンはトランザクションをコミットします。このルーチンをコールすると、ttXlaApplyによってレポートされた一時的なエラー（タイムアウトまたはデッドロック）に応答できます。

この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。

構文

SQLRETURN ttXlaCommit(ttXlaHandle_h handle)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaCommit(xlahandle);

参照

ttXlaConfigBuffer

説明

この関数は、非永続モードでXLAを処理する場合にのみ有効です。

ttXlaConfigBuffer関数を使用すると、XLAステージング・バッファのサイズを設定および取得できます。XLAは、XLAステージング・バッファでトランザクション・ログから取得した更新ログをステージングし、アプリケーションでの読取りを可能にします。

newSizeに値を指定すると、ステージング・バッファの新しいサイズが*newSizeから取得されます。サイズが0（ゼロ）の場合は、ステージング・バッファが未割当てまたはステージング・バッファの割当て禁止を意味します。*oldSizeには、ステージング・バッファの以前のサイズが返されます。また、サイズが以前に設定されていない場合は0（ゼロ）が返されます。

newSizeを指定しない場合は、ステージング・バッファの現在のサイズが*oldSizeに返されます。

ステージング・バッファ・サイズの変更はすぐに実行されます。1つのデータ・ストアに対して設定できるバッファは1つのみです。バッファのサイズが変更されると、ttXlaNextUpdateへの以前のコールによって返された値は無効になります。

この関数の使用方法については、「ステージング・バッファの構成」を参照してください。

構文

SQLRETURN ttXlaConfigBuffer(ttXlaHandle_h handle,  
                  out SQLUBIGINT *oldSize, 
                  SQLUBIGINT *newSize)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
oldSize	out SQLUBIGINT *	ステージング・バッファの現在のサイズ。
newSize	SQLUBIGINT *	ステージング・バッファの新しいサイズ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の宣言を想定しています。

SQLUBIGINT currentSize, requestedSize;

ステージング・バッファのサイズを変更せずにその現在のサイズを確認するには、次のコールを実行します。

rc = ttXlaConfigBuffer(xlahandle, &currentSize, NULL);

ステージング・バッファのサイズを新しいサイズ（400,000バイト）に設定するには、次のコールを実行します。

requestedSize = 400000; rc = ttXlaConfigBuffer(xlahandle, NULL, &requestedSize);

必要に応じて、これらの2つのタイプのコールを組み合せて、現在のサイズの記録と新しいサイズの設定を同時に行うことができます。

最後に、ステージング・バッファを一括削除するには、次のコールを実行します。

requestedSize = 0; rc = ttXlaConfigBuffer(xlahandle, NULL, &requestedSize);

また、install_dir/demo/xla.cファイル内のmain()関数も参照してください。

注意

バッファのサイズを変更すると現在のバッファがコピーされるため、パフォーマンスが大幅に低下する場合があります。より小さいサイズをステージング・バッファに指定し、その小さいサイズに現在の内容を格納できない場合、ステージング・バッファのサイズは変更されず、エラーが返されます。

参照

ttXlaStatus

ttXlaResetStatus

ttXlaDateToODBCCType

説明

内部のDATE値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

構文

SQLRETURN ttXlaDateToODBCCType(void * fromData, 
                             out DATE_STRUCT * returnData)

パラメータ


名前	型	説明
fromData	void *	トランザクション・ログから返されたDATE値へのポインタ。
returnData	out DATE_STRUCT *	変換された日付を保持するように割り当てられた記憶域へのポインタ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードによって返された行からDATE値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

DATE_STRUCT date; 
rc = ttXlaDateToODBCCType(pColVal, &date);

参照

ttXlaDecimalToCString

説明

内部のDECIMAL値を、アプリケーションで使用可能な文字列に変換します。scaleおよびprecisionの値は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。scaleパラメータは、小数点以下の最大桁数を指定します。DECIMAL値が1より大きい場合、precisionパラメータは小数点をはさんだ最大桁数を指定します。DECIMAL値が1より小さい場合、precisionはscaleと同じになります。

この関数の使用方法については、「複合データ型の変換」を参照してください。

構文

SQLRETURN ttXlaDecimalToCString(void *fromData,  
                              out char *returnData, 
                              SQLSMALLINT precision, 
                              SQLSMALLINT scale)

パラメータ


名前	型	説明
fromData	void *	トランザクション・ログから返されたDECIMAL値へのポインタ。
returnData	out char *	変換された文字列を保持するように割り当てられた記憶域へのポインタ。
precision	SQLSMALLINT	fromDataが1より大きい場合、precisionは小数点をはさんだ最大桁数になります。fromData が1より小さい場合、precisionはscaleと同じになります。
scale	SQLSMALLINT	小数点以下の最大桁数。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、ttXlaColDesc_t構造体からoffset、precisionおよびscaleの値を取得し、トランザクション・ログ・レコードに返された行からDECIMAL値pColValを取得するためにoffsetを使用していると想定しています。

char decimalData[50]; 
static ttXlaColDesc_t  colDesc[255]; 
rc = ttXlaDecimalToCString(pColVal, (char*)&decimalData, 
                          colDesc->precision,
                          colDesc->scale);

参照

ttXlaDeleteBookmark

説明

指定したハンドルに関連付けられているブックマークを削除します。ブックマークは、削除するとアクセスできなくなります。ブックマークの識別子は、別のブックマークに再利用できます。ブックマークを削除すると、データ・ストア・ハンドルとの関連が失われ、XLANONEオプションを指定して永続接続をオープンした場合と同じ結果になります。

この関数の使用方法については、「ブックマークの削除」を参照してください。

アクセス制御

アクセス制御が有効になっている場合は、ADMIN権限またはデータ・ストア・オブジェクトの所有権が必要です。

構文

SQLRETURN ttXlaDeleteBookmark(ttXlaHandle_h handle)

パラメータ


名前	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

xlahandleのブックマークを削除します。

rc = ttXlaDeleteBookmark(xlahandle);

参照

ttXlaPersistOpen

ttXlaGetLSN

ttXlaSetLSN

ttXlaError

説明

特定のhandleに対して以前コールした際に発生したエラーの詳細をレポートします。ttXlaErrorへの後続のコールで、複数のエラーが返される場合があります。エラー・スタックは、ttXlaError自体およびttXlaErrorRestart以外の関数をコールするたびに消去されます。

この関数の使用方法については、「XLAエラーの処理」を参照してください。

構文

SQLRETURN ttXlaError(ttXlaHandle_h handle,  
          out SQLINTEGER *errCode, 
          out char *errMessage,  
          SQLINTEGER maxLen,  
          out SQLINTEGER *retLen)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
errCode	out SQLINTEGER *	errMessageバッファにコピーされるエラー・メッセージのコード。
errMessage	out char *	エラー・テキストが保持されるバッファ。
maxLen	SQLINTEGER	errMessageバッファの最大長。
retLen	out SQLINTEGER *	エラー・メッセージの実際のサイズ。

結果

エラー情報が返される場合はSQL_SUCCESSを返し、エラー・スタックにそれ以上エラーがない場合はSQL_NO_DATA_FOUNDを返します。errMessageバッファの大きさが十分でない場合、ttXlaErrorはSQL_SUCCESS_WITH_INFOを返します。

例

エラー・スタックに複数のエラーが存在する可能性があります。この例では、それらをすべて読み取る方法を示します。

char message[100]; 
SQLINTEGER code; 
for (;;) { 
    rc = ttXlaError(xlahandle, &code, message, sizeof (message),
        &retLen); 
    if (rc == SQL_NO_DATA_FOUND) 
        break; 
    if (rc == SQL_ERROR) { 
        printf("Error in fetching error message\n"); 
        break; 
    } 
    else { 
        printf("Error code %d: %s\n", code, message); 
    } 
}

注意

複数のスレッドを使用して単一のXLA接続のTimesTenトランザクション・ログにアクセスすると、同時アクセスを制御するためのラッチが作成されます。なんらかの理由でスレッドでラッチを取得できない場合、XLA関数はSQL_INVALID_HANDLEを返します。

参照

ttXlaErrorRestart

説明

アプリケーションでエラーを再度読み取ることができるように、エラー・スタックをリセットします。この関数の使用方法については、「XLAエラーの処理」を参照してください。

構文

SQLRETURN ttXlaErrorRestart(ttXlaHandle_h handle)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaErrorRestart(xlahandle);

参照

ttXlaError

ttXlaGenerateSQL

説明

更新レコードの結果を示すSQL文を生成します。生成された文は、データ・ストアにもデータベースにも適用されません。かわりに、文は、最大サイズがmaxLenパラメータによって指定される特定のバッファに返されます。バッファの実際のサイズはactualLenによって返されます。更新および削除のレコードの場合、正しいSQLを生成するために、ttXlaGenerateSQLには、NULL値可能でない列に対する主キー索引または一意索引が必要です。

この関数の使用方法については、「TimesTen以外のデータ・ストアへの更新のレプリケート」を参照してください。

構文

SQLRETURN ttXlaGenerateSQL(ttXlaHandle_h handle,  
                ttXlaUpdateDesc_t *record, 
                out char *buffer, 
                SQLINTEGER maxLen, 
                out SQLINTEGER *actualLen)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	ttXlaUpdateDesc_t *	SQLに変換されるレコード。
buffer	out char *	変換されたSQL文の場所。
maxLen	SQLINTEGER	bufferの最大長。
actualLen	out SQLINTEGER *	bufferの実際の長さ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、更新レコードによって表現されるUPDATEに相当するSQL文のテキストを生成します。

ttXlaUpdateDesc_t record; 
char buffer[200]; 
/*  
 *   Get the desired update record into the varable record. 
 */ 
SQLINTEGER actualLength; 
rc = ttXlaGenerateSQL(xlahandle, &record, buffer, 200, 
                      &actualLength);

注意

ttXlaGenerateSQLは、削除された表、またはレコードが生成された後で変更された表に関連付けられている更新レコードに対してはSQL文を生成できません。

参照

ttXlaGetColumnInfo

説明

表内のすべての列に関する情報を取得します。通常、*nreturnedは、colinfoに返される列の数に設定されます。ttXlaColDesc_tデータ型は、ttXlaColDesc_tで定義されています。SystemTableIDまたはuserTableIDは、目的の表について記述します（詳細は、「ttXlaGetTableInfo」を参照）。このコールは、表の定義内の変更に対してシリアライズされます。

この関数の使用方法については、「列記述の取得」を参照してください。

構文

SQLRETURN ttXlaGetColumnInfo(ttXlaHandle_h handle, 
                  SQLUBIGINT systemTableID, 
                  SQLUBIGINT userTableID, 
                  out ttXlaColDesc_t *colinfo, 
                  SQLINTEGER maxcols, 
                  out SQLINTEGER *nreturned)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
systemTableID	SQLUBIGINT	表のシステムID。
userTableID	SQLUBIGINT	表のユーザーID。
colinfo	outttXlaColDesc_t *	maxcols列の個別の記述を保持できる十分な大きさのバッファへのポインタ。
maxcols	SQLINTEGER	colInfoバッファに格納可能な列の最大数。この表にmaxcolsを超える列を含めると、エラーが返されます。
nreturned	out SQLINTEGER *	返される列の数。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaColDesc_t colinfo[20]; SQLUBIGINT systemTableID, userTableID; SQLINTEGER ncols;

システム表識別子を使用して最大20列の記述を取得するには、次のコールを実行します。

rc = ttXlaGetColumnInfo(xlahandle, systemTableID, 0, colinfo, 20, &ncols);

ユーザー表識別子も、同様に使用できます。

rc = ttXlaGetColumnInfo(xlahandle, 0, userTableID, colinfo, 20, &ncols);

返された行内の列データにアクセスする方法の詳細および例については、ttXlaColDesc_tを参照してください。

参照

ttXlaGetTableInfo

ttXlaGetLSN

説明

handleで指定された接続の現行読取りログ順序番号（LSN）を返します。この関数の使用方法については、「XLAブックマーク」を参照してください。

構文

SQLRETURN ttXlaGetLSN(ttXlaHandle_h handle,  
                     out tt_XlaLsn_t *LSN)

パラメータ


名前	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
LSN	out tt_XlaLsn_t *	handleの現行読取りLSN。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現行読取りLSNポインタCurLSNを返します。

tt_XlaLsn_t CurLSN; 
rc = ttXlaGetLSN(xlahandle, &CurLSN);

参照

ttXlaSetLSN

ttXlaGetTableInfo

説明

表内の行に関する情報を取得します（ttXlaTblDesc_tデータ型に関する項を参照）。userTableIDが0（ゼロ）以外の場合は、userTableIDの値を使用して目的の表を検出します。そうでない場合は、systemTableIDの値を使用して表を検出します。両方が0（ゼロ）の場合は、エラーが返されます。記述は、出力パラメータtblinfoに格納されます。このコールは表の定義内の変更に対してシリアライズされます。

構文

SQLRETURN ttXlaGetTableInfo(ttXlaHandle_h handle, 
                 SQLUBIGINT systemTableID, 
                 SQLUBIGINT userTableID,  
                 out ttXlaTblDesc_t *tblinfo)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
systemTableID	SQLUBIGINT	システム表ID。
userTableID	SQLUBIGINT	ユーザー表ID。
tblinfo	out ttXlaTblDesc_t *	行の情報。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaTblDesc_t tabinfo; SQLUBIGINT systemTableID, userTableID;

システム識別子を使用して表の情報を取得するには、ttXlaTableByNameまたは他の方法を使用してシステム表識別子を検出して次のコールを実行します。

rc = ttXlaGetTableInfo(xlahandle, systemTableID, 0, &tabinfo);

また、表の情報は、ユーザー表識別子を使用して取得することもできます。

rc = ttXlaGetTableInfo(xlahandle, 0, userTableID, &tabinfo);

参照

ttXlaGetColumnInfo

ttXlaGetVersion

説明

この関数は、古いバージョンのXLA用に作成されたXLAアプリケーションを新しいバージョンで動作させるために、ttXlaSetVersionと組み合せて使用します。通常、configured versionが古いバージョンで、actual versionが新しいバージョンです。

ttXlaGetVersionは、現在構成されているXLAのバージョンを取得して、configuredVersionパラメータに格納します。基礎となるXLAの実際のバージョンはactualVersionに格納されます。ttXlaSetVersionをコールしたため、コールごとにconfiguredVersionの結果が異なる場合がありますが、actualVersionの結果は同じままです。

この関数の使用方法については、「永続および非永続のXLAモード」を参照してください。

構文

SQLRETURN ttXlaGetVersion(ttXlaHandle_h handle,  
               out ttXlaVersion_t *configuredVersion, 
               out ttXlaVersion_t *actualVersion)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
configuredVersion	out ttXlaVersion_t *	構成されているXLAのバージョン。
actual version	out ttXlaVersion_t *	XLAの実際のバージョン。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の指示を想定しています。

ttXlaVersion_t configured, actual; 
 
現行のバージョン構成を確認するには、次のコールを実行します。

rc = ttXlaGetVersion(xlahandle, &configured, &actual);

参照

ttXlaVersionCompare

ttXlaSetVersion

ttXlaLookup

説明

この関数は、keysパラメータに指定されているキー値を持つ特定の表のレコードを検索します。keysおよびresultレコードの書式は、通常の行の書式と同じです。この関数では、基礎となる表に主キーが必要です。

構文

SQLRETURN ttXlaLookup(ttXlaHandle_h handle,  
            ttXlaTableDesc_t *table, 
            void *keys,  
            out void *result,  
            SQLINTEGER maxsize, 
            out SQLINTEGER *retsize)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
table	ttXlaTblDesc_t *	検索する表。
keys	void *	表に対して定義された構造内のレコード。表の主キーの一部であるキー・レコードの列のみが調べられます。
result	out void *	検出されたレコードは、resultにコピーされます。一致するキー列を持つレコードが存在しない場合は、エラーが返されます。
maxsize	SQLINTEGER	resultバッファに格納可能な最大レコードのサイズ。
retsize	out SQLINTEGER *	レコードの実際のサイズ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、一組の整数キー値を指定してレコードを調べます。このコールの前に、目的の表がtableに記述され、キー列が設定されているレコードがkeybufferに含まれている必要があります。

char keybuffer[100]; 
char recbuffer[2000]; 
ttXlaTableDesc_t table; 
SQLINTEGER recordSize; 
rc = ttXlaLookup(xlahandle, &table, keybuffer, recbuffer, 
                 sizeof (recbuffer), &recordSize);

参照

ttXlaNextUpdate

説明

このコールは、トランザクション・ログから最大maxrecordsの更新レコードをフェッチし、コミットされたトランザクションに関連付けられているレコードをrecordsバッファに返します。実際に返されたレコードの数が出力パラメータnreturnedに記録されます。

トランザクション・ログを永続モードで処理する場合は、ttXlaNextUpdateをコールするたびに、最後に読み取られたレコードにブックマークが再設定され、次のレコードのリストを返すためにttXlaNextUpdateへの次のコールが有効にされます。

この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。

構文

SQLRETURN ttXlaNextUpdate(ttXlaHandle_h handle,  
               out ttXlaUpdateDesc_t ***records,  
               SQLINTEGER maxrecords, 
               out SQLINTEGER *nreturned)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
records	out ttXlaUpdateDesc_t ***	完了したトランザクション・レコードを保持するバッファ。
maxrecords	SQLINTEGER	フェッチされるレコードの最大数。
nreturned	out SQLINTEGER *	実際に返されたレコードの数。使用可能な更新データがない場合は、0（ゼロ）が返されます。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、最大100個のレコードを取得し、各レコードが処理されるループについて記述します。

ttXlaUpdateDesc_t **records;
SQLINTEGER nreturned;
SQLINTEGER i; 
rc = ttXlaNextUpdate(xlahandle, &records, 100, &nreturned); 
/* Check for errors; if none, process the records */ 
for (i = 0; i < nreturned; i++) { 
    process(records[i]); 
} 
 
また、install_dir/demo/persistent_xla/subscriber.cファイル内のinspectTransactions()関数およびinstall_dir/demo/xla.cファイル内のmain()関数も参照してください。

注意

追跡ステータスに関係なく、すべてのデータ定義文に対して更新が生成されます。また、更新はすべてのXLA追跡対象表でのデータ更新処理に対して生成されます。つまり、XLAリーダーによる各処理では、不要な表IDの更新をフィルタ処理する必要があります。

また、表および列に対するアプリケーション・レベルの識別子の割当て、表の追跡ステータスの変更などの特定の処理でも更新が生成されます。

参照

ttXlaNextUpdateWait

ttXlaAcknowledge

ttXlaNextUpdateWait

説明

ttXlaNextUpdate関数と同様の処理を行いますが、使用可能なレコードがログにない場合に待機する秒数を指定するパラメータsecondsがあります。実際に待機する秒数は、secondsに指定された値より最大で2秒長くなる場合があります。

この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。

構文

SQLRETURN ttXlaNextUpdateWait(ttXlaHandle_h handle,  
                   out ttXlaUpdateDesc_t *** records,  
                   SQLINTEGER maxrecords, 
                   out SQLINTEGER * nreturned, 
                   SQLINTEGER seconds)

パラメータ


名前	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
records	out ttXlaUpdateDesc_t ***	完了したトランザクション・レコードを保持するバッファ。
maxrecords	SQLINTEGER	フェッチされるレコードの最大数。
nreturned	out SQLINTEGER *	実際に返されたレコードの数。secondsの待機時間内に使用可能な更新データがない場合は、0（ゼロ）が返されます。
seconds	SQLINTEGER	ログが空の場合に待機する時間（秒）。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

最大100個のレコードを取得し、使用可能なレコードがログにない場合に最大60秒待機します。

ttXlaUpdateDesc_t **records; 
SQLINTEGER nreturned; 
SQLINTEGER i; 
rc = ttXlaNextUpdateWait(xlahandle, &records, 100, 
                         &nreturned, 60); 
/* Check for errors; if none, process the records */ 
for (i = 0; i < nreturned; i++) { 
    process(records[i]); 
}

参照

ttXlaNextUpdate

ttXlaAcknowledge

ttXlaOpenTimesTen

説明

TimesTenデータ・ストアに対するトランザクション・ログ・ハンドルを初期化し、非永続モードでのトランザクション・ログへのアクセスを有効にします。hdbcパラメータは、TimesTenデータ・ストアに対するODBC接続ハンドルで、更新の適用に使用します。ttXlaCloseでクローズするまで、この接続に対して他のODBCコールは発行しないでください。handleパラメータは、このコールによって初期化し、更新を適用する後続の各コールで指定する必要があります。

非永続モードでは、いずれの時点でも1つのアプリケーションのみをログから読み取ることができます。この関数の使用方法については、「非永続モードでのXLAの初期化」を参照してください。

注意: 多くのアプリケーションで、ttXlaPersistOpenを使用して、XLAを永続モードで初期化する必要があります。

アクセス制御

アクセス制御が有効になっている場合は、WRITE権限またはデータ・ストア・オブジェクトの所有権が必要です。

注意: セッションをオープンすると、ハンドルへのXLAコールに対して権限の確認は続行されません。

構文

SQLRETURN ttXlaOpenTimesTen(SQLHDBC hdbc,  
                         out ttXlaHandle_h *handle)

パラメータ


パラメータ	型	説明
hdbc	SQLHDBC	データ・ストアのODBCハンドル。
handle	out ttXlaHandle_h *	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

トランザクション・ログを非永続モードでオープンし、ODBC接続のxlahandleという名前のハンドルを返すには、次のコールを実行します。

SQLHDBC hdbc;
ttXlaHandle_h xlahandle; 
rc = ttXlaOpenTimesTen(hdbc, &xlahandle);

注意

TimesTenでは、同じXLAハンドルに対して複数のスレッドは使用しないことをお薦めします。マルチスレッド・アプリケーションでは、ttXlaPersistOpenを使用してスレッドごとに別々のXLAハンドルを作成する必要があります。複数のスレッドで同じXLAハンドルを使用する必要がある場合は、1つのスレッドのみが一度に1つのXLA処理を実行できるように、mutexを使用してそのXLAハンドルへのスレッド・アクセスをシリアライズします。

参照

ttXlaPersistOpen

説明

TimesTenデータ・ストアに対するトランザクション・ログ・ハンドルを初期化して、永続モードでのトランザクション・ログへのアクセスを有効にします。hdbcパラメータは、TimesTenデータ・ストアへのODBC接続ハンドルです。ODBC接続ごとに1つのXLAハンドルのみを作成します。ODBC接続に対してXLAハンドルを作成した場合は、ttXlaCloseでクローズするまで、ODBC接続に対して他のODBCコールは発行しないでください。

tagは、永続ブックマークを識別する文字列です（「XLAブックマーク」を参照）。tagでは、optionsパラメータを指定して、新しいブックマークかシステムにすでに存在するブックマークかを識別できます。handleパラメータは、このコールによって初期化され、XLAに対する後続の各コールで指定する必要があります。

一部の処理は、ブックマークなしで実行できます。これらのタイプの処理を実行する場合は、XLANONEオプションを使用して、ブックマークなしでログにアクセスできます。次に、ブックマークなしでは実行できない処理を示します。

永続モードでは、複数のアプリケーションで同時にログから読取りを実行できます。この関数の使用方法については、「XLAの初期化およびXLAハンドルの取得」を参照してください。

注意: 永続モードは、ディスクベースのロギングでのみサポートされています。

アクセス制御

アクセス制御が有効になっている場合は、WRITE権限またはデータ・ストア・オブジェクトの所有権が必要です。

注意: セッションをオープンすると、ハンドルへのXLAコールに対して権限の確認は続行されません。

構文

SQLRETURN ttXlaPersistOpen(SQLHDBC hdbc,  
                SQLCHAR * tag,  
                SQLUINTEGER options,  
                out ttXlaHandle_h * handle)

パラメータ


パラメータ	型	説明
hdbc	SQLHDBC	データ・ストアのODBCハンドル。
tag	SQLCHAR *	永続ブックマークの識別子。optionsがXLANONEに設定されている場合はNULLを指定できます。許容最大長は31です。
options	SQLUINTEGER	ブックマーク・オプションは、次のとおりです。 XLANONE: ブックマークなしで接続します。tagフィールドは無視されます。 XLACREAT: 新しいブックマークを作成します。ブックマークがすでに存在する場合は失敗します。 XLAREUSE: 既存のブックマークに関連付けます。ブックマークが存在しない場合は失敗します。
handle	out ttXlaHandle_h *	このコールによって返されるトランザクション・ログ・ハンドル。このコールによって領域が割り当てられます。領域を解放するには、ttXlaCloseをコールする必要があります。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。この例では、トランザクション・ログを永続モードでオープンし、xlahandleというハンドルを返して、mybookmarkという新しいブックマークを作成します。

SQLHDBC hdbc;
ttXlaHandle_h xlahandle; 
rc = ttXlaPersistOpen(hdbc, ( SQLCHAR*)mybookmark, 
                      XLACREAT, &xlahandle);

注意

マルチスレッド・アプリケーションでは、スレッドごとに別々のXLAハンドルを作成する必要があります。複数のスレッドで同じXLAハンドルを使用する必要がある場合、1つのスレッドのみが一度に1つのXLA処理を実行できるように、mutexを使用してそのXLAハンドルへのスレッド・アクセスをシリアライズします。

参照

ttXlaResetStatus

説明

ttXlaStatusによって返されるttXlaStatus_t構造体にレポートされるすべてのXLAのステータス・カウンタをリセットします。現在、xlabufminfreeの値のみがリセットされます。この関数の使用方法については、「バッファ・ステータスの取得およびリセット」を参照してください。

構文

SQLRETURN ttXlaResetStatus(ttXlaHandle_h handle)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

次の例では、XLAのステータス・カウンタをリセットします。

rc = ttXlaResetStatus(xlahandle);

参照

ttXlaConfigBuffer

ttXlaStatus

ttXlaRollback

説明

ハンドルに対して適用中の現行のトランザクションをロールバックします。このルーチンをコールすると、ttXlaApplyによってレポートされた一時的なエラー（タイムアウトまたはデッドロック）に応答できます。

この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。

構文

SQLRETURN ttXlaRollback(ttXlaHandle_h handle)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaRollback(xlahandle);

参照

ttXlaSetLSN

説明

handleで指定されたデータ・ストアの現行読取りログ順序番号（LSN）を設定します。指定されたLSNの値は、ttXlaGetLSNから返される必要があります（ユーザーが作成した値、現在のブックマークの初期読取りLSNより小さい値は使用できません）。

この関数の使用方法については、「XLAブックマーク」を参照してください。

構文

SQLRETURN ttXlaSetLSN(ttXlaHandle_h handle,  
                     tt_XlaLsn_t *LSN)

パラメータ


名前	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
LSN	tt_XlaLsn_t *	handleの新しい読取りLSN。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現行読取りLSNポインタをCurLSNに設定します。

tt_XlaLsn_t CurLSN; 
rc = ttXlaSetLSN(xlahandle, &CurLSN);

参照

ttXlaGetLSN

ttXlaSetVersion

説明

アプリケーションで使用されるXLAのバージョンを設定します。このバージョンは、ttXlaGetVersionで返されるバージョンと同じか、または以前のバージョンである必要があります。

この関数の使用方法については、「永続および非永続のXLAモード」を参照してください。

構文

SQLRETURN ttXlaSetVersion(ttXlaHandle_h handle,  
                        ttXlaVersion_t *version)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
version	ttXlaVersion_t *	XLAの必要なバージョン。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

構成されているバージョンをrequestedVersionで指定された値に設定するには、次のコールを実行します。

rc = ttXlaSetVersion(xlahandle, &requestedVersion);

参照

ttXlaVersionCompare

ttXlaGetVersion

ttXlaStatus

説明

この関数は、非永続モードでXLAを処理する場合にのみ有効です。

現在のXLAのステータスを取得して、*statusパラメータに格納します。この関数の使用方法については、「バッファ・ステータスの取得およびリセット」を参照してください。

構文

ttXlaStatus(ttXlaHandle_h handle, out ttXlaStatus_t *status)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
status	out ttXlaStatus_t *	現在のXLAのステータス。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現在のXLAのステータスを取得します。

ttXlaStatus_t s; 
rc = ttXlaStatus(xlahandle, &s);

参照

ttXlaConfigBuffer

ttXlaResetStatus

ttXlaTableByName

説明

表またはビューの所有者および名前を指定して、表またはマテリアライズド・ビューのシステム表識別子およびユーザー表識別子を検出します。この関数の使用方法については、「更新を監視する表の指定」を参照してください。

構文

SQLRETURN ttXlaTableByName(ttXlaHandle_h handle, 
                char *owner, 
                char *name, 
                out SQLUBIGINT *sysTableID, 
                out SQLUBIGINT *userTableID)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
owner	char *	表またはビューの所有者の文字列。
name	char *	表またはビューの名前。
sysTableID	out SQLUBIGINT *	システム表IDが返されます。
userTableID	out SQLUBIGINT *	ユーザー表IDが返されます。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

表PURCHASING.INVOICESに関連付けられているシステム表IDおよびユーザー表IDを取得するには、次のコールを実行します。

SQLUBIGINT sysTableID; 
SQLUBIGINT userTableID; 
rc = ttXlaTableByName(xlahandle, "PURCHASING", "INVOICES",
                      &sysTableID, &userTableID);

参照

ttXlaTableStatus

ttXlaTableCheck

説明

レプリケーション・メカニズムとしてXLAを使用する場合、この関数は、マスター・データ・ストアから受信したttXlaTblDesc_t内の名前付き表が、handleに関連付けられているサブスクライバ・データ・ストアまたはデータベースと互換性があることを検証します。compatパラメータは、表に互換性があるかどうかを示します。

この関数の使用方法については、「データ・ストア間での表の互換性の確認」を参照してください。

構文

SQLRETURN ttXlaTableCheck(ttXlaHandle_h handle,  
               ttXlaTblDesc_t *table, 
               ttXlaColDesc_t *columns, 
               out SQLINTEGER *compat)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
table	ttXlaTblDesc_t *	表記述。
columns	ttXlaColDesc_t *	表の列記述。
compat	out SQLINTEGER *	互換性情報を返します。 1 =表に互換性がある。 0 =表に互換性がない。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、表の互換性を確認します。

SQLINTEGER compat; 
ttXlaTblDesc_t table; 
ttXlaColDesc_t columns[20]; 
/* 
 * Get the desired table and column definitions into 
 * the variables "table" and "columns" 
 */ 
rc = ttXlaTableCheck(xlahandle, &table, columns, &compat); 
if (compat) { 
    /* 
     * Compatible 
     */ 
} 
else { 
    /* 
     * Not compatible or some other error occurred 
     */ 
}

参照

ttXlaTableStatus

説明

表の更新ステータスを*oldstatusに返します。表は、ユーザーID（userTableID）またはシステムID（systemTableID）のいずれかで識別します。userTableIDが0（ゼロ）以外の場合は、userTableIDが表の識別に使用されます。そうでない場合は、systemTableIDが使用されます。両方が0（ゼロ）の場合は、エラーが返されます。

newstatusに値を指定すると、更新ステータスが*newstatusに設定されます。ステータスが0（ゼロ）以外の場合は、systemTableIDで指定された表がXLAで使用可能であることを意味します。0（ゼロ）の場合は、表が追跡されないことを意味します。表の更新ステータスへの変更は、すぐに有効になります。

更新が実行された時点で表の更新追跡が有効になっていた場合にのみ、表への更新が追跡されます。このコールは、基礎となる表への更新に対してシリアライズされます。このため、表を更新するトランザクションは、表のステータスが変更される完全前または完全後に実行されます。

注意: 表またはビューを監視するためにttXlaTableStatusによって作成されたサブスクリプションはグローバルです。このため、1つのXLAリーダーによってサブスクライブされている表またはビューは、トランザクション・ログの他のすべてのXLAリーダーによっても参照されます。

この関数の使用方法については、「更新を監視する表の指定」を参照してください。

構文

SQLRETURN ttXlaTableStatus(ttXlaHandle_h handle, 
                SQLUBIGINT systemTableID, 
                SQLUBIGINT userTableID,  
                out SQLINTEGER *oldstatus, 
                SQLINTEGER *newstatus)

パラメータ


パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
systemTableID	SQLUBIGINT	表のシステムID。
userTableID	SQLUBIGINT	表のユーザーID。
oldstatus	out SQLINTEGER *	XLAのステータスは、次のとおりです。 On = 1またはOff = 0
newstatus	SQLINTEGER *	XLAのステータスは、次のとおりです。 On = 1またはOff = 0

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

次の例では、ttXlaTableByNameまたは他のなんらかの方法を使用して、システム表識別子またはユーザー表識別子が検出されていることを想定しています。

この例では、次の宣言を想定しています。

SQLUBIGINT systemTableID; SQLUBIGINT userTableID; SQLINTEGER currentStatus, requestedStatus;

システム表識別子を指定して表のステータスを検出するには、次のコールを実行します。

/* Get system table identifier into systemTableID, then ... */ rc = ttXlaTableStatus(xlahandle, systemTableID, 0, &currentStatus, NULL);

currentStatusの値は、表の更新追跡が有効になっている場合は0（ゼロ）以外になり、そうでない場合は0（ゼロ）になります。

システム表識別子を指定して表の更新追跡を有効にするには、次のように、リクエストするステータスを1に設定します。

requestedStatus = 1; rc = ttXlaTableStatus(xlahandle, systemTableID, 0, NULL, &requestedStatus);

新しい更新追跡ステータスを設定し、1回のコールで現在のステータスを取得できます。次に例を示します。

requestedStatus = 1; rc = ttXlaTableStatus(xlahandle, systemTableID, 0, &currentStatus, &requestedStatus);

前述のコールでは、システム表識別子による表の更新追跡が有効になり、以前の更新追跡ステータスが変数currentStatusに取得されます。

これらのすべての例は、ユーザー表識別子を使用しても実行できます。ユーザー表識別子によって表の更新追跡ステータスを取得するには、次のコールを実行します。

/* Get system table identifier into userTableID, then ... */ rc = ttXlaTableStatus(xlahandle, 0, userTableID, &currentStatus, NULL);

参照

ttXlaTableByName

ttXlaTimeToODBCCType

説明

内部のTIME値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

構文

SQLRETURN ttXlaTimeToODBCCType (void *fromData,  
                              out TIME_STRUCT *returnData)

パラメータ


名前	型	説明
fromData	void *	トランザクション・ログから返されたTIME値へのポインタ。
returnData	out TIME_STRUCT *	変換された時間を保持するように割り当てられた記憶域へのポインタ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードによって返された行からTIME値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

TIME_STRUCT time; 
rc = ttXlaTimeToODBCCType(pColVal, &time);

参照

説明

内部のTIMESTAMP値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

構文

SQLRETURN ttXlaTimeStampToODBCCType(void *fromData,  
                             out TIMESTAMP_STRUCT *returnData)

パラメータ


名前	型	説明
fromData	void *	トランザクション・ログから返されたTIMESTAMP値へのポインタ。
returnData	out TIMESTAMP_ STRUCT *	変換されたタイムスタンプを保持するように割り当てられた記憶域へのポインタ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードによって返された行からTIMESTAMP値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

TIMESTAMP_STRUCT timestamp; 
rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);

参照